main: Add a better comment about shifting the modal stack

It took me a few minutes to realize why, so let's just add this
in for future reference.

https://bugzilla.gnome.org/show_bug.cgi?id=690965

diff --git a/js/ui/main.js b/js/ui/main.js
index 8c9136a5a48cb92d3d1b3b32c08d777152aeca89..b907eb9c20289897795a3cdeb02302b78bef1ace 100644 (file)
--- a/js/ui/main.js
+++ b/js/ui/main.js
@@ -606,6 +606,21 @@ function popModal(actor, timestamp) {
         keybindingMode = record.keybindingMode;
         global.stage.set_key_focus(record.prevFocus);
     } else {
+        // If we have:
+        //     global.stage.set_focus(a);
+        //     Main.pushModal(b);
+        //     Main.pushModal(c);
+        //     Main.pushModal(d);
+        //
+        // then we have the stack:
+        //     [{ prevFocus: a, actor: b },
+        //      { prevFocus: b, actor: c },
+        //      { prevFocus: c, actor: d }]
+        //
+        // When actor c is destroyed/popped, if we only simply remove the
+        // record, then the focus stack will be [a, c], rather than the correct
+        // [a, b]. Shift the focus stack up before removing the record to ensure
+        // that we get the correct result.
         let t = modalActorFocusStack[modalActorFocusStack.length - 1];
         if (t.prevFocus)
             t.prevFocus.disconnect(t.prevFocusDestroyId);